home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 2 / Apprentice-Release2.iso / Source Code / C / Libraries / stdwin / Doc / man / textedit.man < prev    next >
Encoding:
Text File  |  1988-06-23  |  6.3 KB  |  236 lines  |  [TEXT/????]
  1. .TH TEXTEDIT 3
  2. .SH NAME
  3. Textedit \- text-editing package for STDWIN
  4. .SH SYNOPSIS
  5. .nf
  6. .ft C
  7. #include "stdwin.h"
  8.  
  9. TEXTEDIT *tealloc(WINDOW *win, int left, int top, int width);
  10. TEXTEDIT *tecreate(WINDOW *win, int left, int top, int right, int bottom);
  11. void tefree(TEXTEDIT *tp);
  12. void tedestroy(TEXTEDIT *tp);
  13.  
  14. void tedraw(TEXTEDIT *tp);
  15. void tedrawnew(TEXTEDIT *tp, int left, int top, int right, int bottom);
  16. void temove(TEXTEDIT *tp, int left, int top, int width);
  17. void temovenew(TEXTEDIT *tp, int left, int top, int right, int bottom);
  18.  
  19. void tesetfocus(TEXTEDIT *tp, int foc1, int foc2);
  20. void tereplace(TEXTEDIT *tp, char *str);
  21. void tesetbuf(TEXTEDIT *tp, char *buf, int buflen);
  22.  
  23. void tearrow(TEXTEDIT *tp, int code);
  24. void tebackspace(TEXTEDIT *tp);
  25. bool teclicknew(TEXTEDIT *tp, int h, int v, bool extend);
  26. bool tedoubleclick(TEXTEDIT *tp, int h, int v);
  27. bool teevent(TEXTEDIT *tp, EVENT *ep);
  28.  
  29. #define teclick(tp, h, v) teclicknew(tp, h, v, FALSE)
  30. #define teclickextend(tp, h, v) teclicknew(tp, h, v, TRUE)
  31.  
  32. char *tegettext(TEXTEDIT *tp);
  33. int tegetlen(TEXTEDIT *tp);
  34. int tegetnlines(TEXTEDIT *tp);
  35. int tegetfoc1(TEXTEDIT *tp);
  36. int tegetfoc2(TEXTEDIT *tp);
  37. int tegetleft(TEXTEDIT *tp);
  38. int tegettop(TEXTEDIT *tp);
  39. int tegetright(TEXTEDIT *tp);
  40. int tegetbottom(TEXTEDIT *tp);
  41.  
  42. int wdrawpar(int h, int v, char *text, int width);
  43. int wparheight(char *text, int width);
  44. .ft 1
  45. .fi
  46. .SH DESCRIPTION
  47. .I Textedit
  48. is the standard text-editing package for STDWIN.
  49. It allows you to designate any part of a window as a ``text-editing''
  50. area, in which the user can see or edit arbitrary text.
  51. Until I find the time and the mental rest to write a decent manual,
  52. you'll have to do with the example and hints on this man page.
  53. .PP
  54. A textedit area need not occupy an entire window, and there can be
  55. more than one textedit area in a given window.
  56. Consequently, textedit areas are not resized automatically when their
  57. window is resized, and the document size is not set automatically when
  58. the textedit area's size changes.
  59. If you want to use a single textedit area in a window, and want them to
  60. be coupled more tightly, use the
  61. .I editwin
  62. package instead.
  63. .PP
  64. The functions
  65. .I wdrawpar
  66. and
  67. .I wparheight
  68. draw a paragraph of text exactly like the
  69. .I textedit
  70. routines would draw it, without the need to allocate a textedit data
  71. structure for it.
  72. .I Wdrawpar
  73. returns the ``v'' coordinate of the bottom of the paragraph drawn, and
  74. .I wparheight
  75. returns its height.
  76. .PP
  77. Available routines are:
  78. .IP tealloc
  79. .IP tecreate
  80. .IP tefree
  81. .IP tedestroy
  82. .IP tedraw
  83. .IP tedrawnew
  84. .IP temove
  85. .IP temovenew
  86. .IP tesetfocus
  87. .IP tereplace
  88. .IP tesetbuf
  89. .IP tearrow
  90. .IP tebackspace
  91. .IP teclicknew
  92. .IP tedoubleclick
  93. .IP teevent
  94. .IP teclick
  95. .IP teclickextend
  96. .IP tegettext
  97. .IP tegetlen
  98. .IP tegetnlines
  99. .IP tegetfoc1
  100. .IP tegetfoc2
  101. .IP tegetleft
  102. .IP tegettop
  103. .IP tegetright
  104. .IP tegetbottom
  105. .IP wdrawpar
  106. .IP wparheight
  107. .SH EXAMPLE
  108. .nf
  109. .ft C
  110. #include "stdwin.h"
  111.  
  112. WINDOW *win;
  113. TEXTEDIT *tp;
  114.  
  115. void drawproc(win, left, top, right, bottom) WINDOW *win; {
  116.     tedrawnew(tp,left, top, right, bottom);
  117. }
  118.  
  119. main() {
  120.     winit();
  121.     win= wopen("Hello world", &drawproc);
  122.     tp= tecreate(win, 20, 20, 200, 200);
  123.     tereplace(tp, "Guido is gek");
  124.     for (;;) {
  125.         EVENT e;
  126.         wgetevent(&e);
  127.         if (teevent(tp, &e)) continue; /* Event has been handled */
  128.         if (e.type == WE_COMMAND && e.u.command == WC_CLOSE) break;
  129.     }
  130.     wdone();
  131.     exit(0);
  132. }
  133. .ft 1
  134. .fi
  135. .SH HINTS
  136. .I Tedestroy
  137. calls
  138. .I wchange
  139. for the area occupied by the textedit area, and then calls
  140. .IR tefree ;
  141. .I tefree
  142. gets rid of the data structures allocated for it.
  143. .PP
  144. .I Tesetbuf
  145. ``gives the buffer away.''
  146. That is, you should have allocated the buffer using
  147. .IR malloc (3),
  148. but you shouldn't call
  149. .I free
  150. to get rid of it \- a pointer to the buffer is incorporated in the
  151. textedit data structures, and it will be freed later by
  152. .I tefree.
  153. Don't pass a buffer that wasn't allocated through
  154. .IR malloc (3)!
  155. .PP
  156. .I Tegettext
  157. returns a pointer to the internal buffer used to represent the text.
  158. Subsequent calls to textedit routines that modify the buffer may
  159. invalidate this pointer.
  160. You shouldn't modify the text found there.
  161. To get the text selected in the focus, copy the substring found between
  162. positions
  163. .I tegetfoc1
  164. and
  165. .I tegetfoc2,
  166. for example:
  167. .nf
  168. .ft C
  169. /* Copy focus text into buffer, whose size is len */
  170. getfocus(tp, buf, len) TEXTEDIT *tp; char *buf; {
  171.     int f1= tegetfoc1(tp), f2= tegetfoc2(tp);
  172.     char *text= tegettext(tp);
  173.     if (f2-f1 < len) len= f2-f1+1;
  174.     strncpy(buf, len-1, text+f1);
  175.     buf[len-1]= '\0';
  176. }
  177. .ft 1
  178. .fi
  179. .SH DIAGNOSTICS
  180. .I Tealloc
  181. and
  182. .I tecreate
  183. return NULL when they could not get all the necessary memory.
  184. The other routines may fail but there is no way to find out.
  185. .SH SEE ALSO
  186. STDWIN documentation
  187. .br
  188. editwin(3)
  189. .SH AUTHOR
  190. Guido van Rossum
  191. .SH BUGS
  192. Textedit areas always grow and shrunk automaticatically at the bottom.
  193. Therefore,
  194. .I tecreate
  195. ignores the bottom coordinate.
  196. .br
  197. When a textedit area shrinks more than a line at a time, garbage may
  198. remain on the screen between the old and the new bottom position.
  199. .br
  200. The text attributes (font, size and style) in effect when any of the
  201. textedit routines are called must be those that were in effect when the
  202. textedit area was created.  (The routines should save and restore the
  203. text attributes, but currently they don't.)
  204. .br
  205. The constants TRUE and FALSE used in the #include file are not defined
  206. there, even though the typedef bool is.
  207. .br
  208. Beware that the last argument to
  209. .I tealloc
  210. and
  211. .I temove
  212. is the width of the textedit area on the screen, not its right
  213. coordinate!
  214. .br
  215. It is a pain that there are ``new'' and ``old'' versions of routines
  216. like tealloc, tedraw, temove and teclick.
  217. The old routines should not be used any more, and the new ones should be
  218. renamed to the old names.
  219. .br
  220. .I Wdrawpar
  221. and
  222. .I wparheight
  223. are easy to use but not particularly efficient; they allocate a textedit
  224. data structure, call internal textedit routines to do the work, and then
  225. deallocate the data structure again.
  226. .br
  227. Missing functionality:
  228. a way to affect the line breaking algorithm;
  229. a way to display text centered or with justified margins;
  230. a way to disable changes while still passing events (for selection, etc.);
  231. more keyboard editing functions (begin/end of line/file, etc.);
  232. a way to suppress the automatic growing of the textedit area;
  233. a way to specify a margin around the textedit area where mouse clicks
  234. are still accepted by
  235. .I teevent.
  236.